Greptile Summary

Removes the packages/*/src/data_designer/** path filter from the docs-preview workflow so it no longer fires on pure code-only PRs. The fix is correct in motivation but slightly over-broad: mkdocs.yml uses mkdocstrings to auto-generate the Code Reference section from those same source directories, so docstring-only PRs will no longer receive a preview either.

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    PR[Pull Request opened / synchronized] --> PathCheck{Path filter match?}
    PathCheck -->|docs/** changed| Trigger[Run docs-preview workflow]
    PathCheck -->|mkdocs.yml changed| Trigger
    PathCheck -->|.github/workflows/docs-preview.yml changed| Trigger
    PathCheck -->|packages/ source changed ONLY| Skip[Workflow skipped]
    Trigger --> Build[Build MkDocs site]
    Build --> Deploy[Deploy to Cloudflare Pages]
    Deploy --> Comment[Post preview URL comment on PR]
    Skip --> NoPreview[No preview generated]
    style Skip fill:#f96,color:#000
    style NoPreview fill:#f96,color:#000

This is a comment left during a code review.
Path: .github/workflows/docs-preview.yml
Line: 3-9

Comment:
**Source-code docstring changes no longer trigger a preview**

`mkdocs.yml` configures `mkdocstrings` to render the entire **Code Reference** section directly from docstrings in `packages/*/src/data_designer/**`, and its `watch` block lists the same paths. A PR that only updates a docstring, adds a new public class, or renames a parameter will no longer receive a Cloudflare preview, so reviewers won't be able to inspect the rendered API reference change in the PR.

Consider re-adding a narrower path that targets only the source files most likely to affect rendered output, for example:

```yaml
- "packages/*/src/data_designer/**/*.py"
```

That still prevents the broader infra/test churn from triggering previews while keeping the mkdocstrings-backed pages covered.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into andreatgretel/f..." | Re-trigger Greptile}

Docs preview: https://e651afbe.dd-docs-preview.pages.dev

Notebook tutorials are placeholder-only in previews.

Review: PR #515 — fix: restrict docs-preview workflow to actual docs changes

Summary

This single-line PR removes the packages/*/src/data_designer/** glob from the paths trigger in .github/workflows/docs-preview.yml. The stated goal is to stop code-only PRs from wastefully triggering a full docs preview build + Cloudflare Pages deploy.

Changed files: 1 (.github/workflows/docs-preview.yml — 0 additions, 1 deletion)

Findings

1. [Medium] Docs build depends on source code via mkdocstrings

The mkdocstrings plugin is configured in mkdocs.yml to render API reference pages from Python docstrings located under packages/*/src/:

- mkdocstrings:
    handlers:
      python:
        paths:
          - packages/data-designer-config/src
          - packages/data-designer-engine/src
          - packages/data-designer/src

There are 12+ API reference pages in docs/code_reference/ that use ::: data_designer.* autodoc directives. When a PR modifies a public docstring, function signature, or class definition in the source packages, the rendered API reference will change — but with this filter removed, no docs preview will be generated for those PRs.

This means a contributor changing a public API surface (renaming a parameter, updating a docstring, removing a class) will not get a docs preview showing the impact on the published reference docs. The previous broad filter was over-inclusive (it fired on any source change, not just public API changes), but removing it entirely swings to under-inclusive.

Suggestion: Consider a narrower filter that still covers the API-surface files. For example:

- "packages/*/src/data_designer/**/config_builder.py"
- "packages/*/src/data_designer/**/column_configs.py"
- "packages/*/src/data_designer/config/**"

Or accept the trade-off and document that contributors should manually trigger a docs preview (or check locally) when changing public APIs.

2. [Low] No follow-up for local docs verification guidance

The PR description's test plan covers CI trigger behavior but doesn't mention updating contributor docs (e.g., DEVELOPMENT.md or CONTRIBUTING.md) to note that source-code changes affecting API docs now require manual mkdocs build verification. This is minor — contributors familiar with the project likely know this — but worth noting for completeness.

3. [Info] The change itself is correct and safe

The YAML syntax is valid. The remaining path filters (docs/**, mkdocs.yml, .github/workflows/docs-preview.yml) are the right set for pure-docs changes. The deletion does not affect any other workflow or job.

Verdict

Approve with comment. The change is correct for its stated goal (stop code-only PRs from triggering docs builds) and is low-risk. However, the mkdocstrings dependency on source files means API-reference accuracy in previews will regress for source-only PRs. The team should make a deliberate call on whether that trade-off is acceptable or whether a narrower path filter targeting public API modules would be preferable.